1. Module srfi-4
    1. CHICKEN implementation specifics and extensions
    2. Blob conversions
    3. Subvectors
    4. Vector I/O
  2. SRFI-4 specification
    1. Datatypes
    2. External representation
    3. Predicates
    4. Constructors
    5. Length
    6. Getters
    7. Setters
    8. Conversions
    9. Release number vectors allocated in static memory

Module srfi-4

Homogeneous numeric vector datatypes. Also see the original SRFI-4 document.

When loaded, the feature identifier srfi-4 is defined.

CHICKEN implementation specifics and extensions

Blob conversions

As a SRFI-4 vector is basically just a blob wrapped by a SRFI-4 type "header object" to structure its contents, there are several procedures which can convert between blobs and SRFI-4 vectors.

[procedure] (u8vector->blob U8VECTOR)
[procedure] (s8vector->blob S8VECTOR)
[procedure] (u16vector->blob U16VECTOR)
[procedure] (s16vector->blob S16VECTOR)
[procedure] (u32vector->blob U32VECTOR)
[procedure] (s32vector->blob S32VECTOR)
[procedure] (u64vector->blob U64VECTOR)
[procedure] (s64vector->blob S64VECTOR)
[procedure] (f32vector->blob F32VECTOR)
[procedure] (f64vector->blob F64VECTOR)
[procedure] (u8vector->blob/shared U8VECTOR)
[procedure] (s8vector->blob/shared S8VECTOR)
[procedure] (u16vector->blob/shared U16VECTOR)
[procedure] (s16vector->blob/shared S16VECTOR)
[procedure] (u32vector->blob/shared U32VECTOR)
[procedure] (s32vector->blob/shared S32VECTOR)
[procedure] (u64vector->blob/shared U64VECTOR)
[procedure] (s64vector->blob/shared S64VECTOR)
[procedure] (f32vector->blob/shared F32VECTOR)
[procedure] (f64vector->blob/shared F64VECTOR)

Each of these procedures return the contents of the given vector as a 'packed' blob. The byte order in that vector is platform-dependent (for example little-endian on an Intel processor). The /shared variants return a blob that shares memory with the contents of the vector, the others will copy the contents of the SRFI-4 vector's internal blob object.

[procedure] (blob->u8vector BLOB)
[procedure] (blob->s8vector BLOB)
[procedure] (blob->u16vector BLOB)
[procedure] (blob->s16vector BLOB)
[procedure] (blob->u32vector BLOB)
[procedure] (blob->s32vector BLOB)
[procedure] (blob->u64vector BLOB)
[procedure] (blob->s64vector BLOB)
[procedure] (blob->f32vector BLOB)
[procedure] (blob->f64vector BLOB)
[procedure] (blob->u8vector/shared BLOB)
[procedure] (blob->s8vector/shared BLOB)
[procedure] (blob->u16vector/shared BLOB)
[procedure] (blob->s16vector/shared BLOB)
[procedure] (blob->u32vector/shared BLOB)
[procedure] (blob->s32vector/shared BLOB)
[procedure] (blob->u64vector/shared BLOB)
[procedure] (blob->s64vector/shared BLOB)
[procedure] (blob->f32vector/shared BLOB)
[procedure] (blob->f64vector/shared BLOB)

Each of these procedures return a vector where the argument BLOB is taken as a 'packed' representation of the contents of the vector. The /shared variants return a vector that shares memory with the contents of the blob, the others will copy the blob.

Subvectors

[procedure] (subu8vector U8VECTOR FROM TO)
[procedure] (subu16vector U16VECTOR FROM TO)
[procedure] (subu32vector U32VECTOR FROM TO)
[procedure] (subu64vector U32VECTOR FROM TO)
[procedure] (subs8vector S8VECTOR FROM TO)
[procedure] (subs16vector S16VECTOR FROM TO)
[procedure] (subs32vector S32VECTOR FROM TO)
[procedure] (subs64vector S32VECTOR FROM TO)
[procedure] (subf32vector F32VECTOR FROM TO)
[procedure] (subf64vector F64VECTOR FROM TO)

Creates a fresh number vector of the same type as the argument vector with the elements at the positions FROM up to but not including TO.

Vector I/O

[procedure] (read-u8vector [LENGTH [PORT]])

Reads LENGTH bytes from the PORT and returns a fresh u8vector, or as many as are available before end-of-file is encountered. PORT defaults to the value of (current-input-port). If no bytes are available before the end-of-file, #!eof is returned.

If LENGTH is #f, the vector will be filled completely until end-of-file is reached.

[procedure] (read-u8vector! LENGTH U8VECTOR [PORT [START]])

Reads LENGTH bytes from the PORT writing the read input into U8VECTOR beginning at START (or 0 if not given). PORT defaults to the value of (current-input-port).

If LENGTH is #f, the vector will be filled completely until end-of-file is reached. This procedure returns the number of bytes read.

[procedure] (write-u8vector U8VECTOR [PORT [START [END]]])

Writes the bytes U8VECTOR between the indices START (inclusive) and END (exclusive) to PORT.

PORT defaults to the value of (current-output-port).

SRFI-4 specification

SRFI-4 describes a set of datatypes for vectors whose elements are of the same numeric type (signed or unsigned exact integer or inexact real of a given precision). These datatypes support operations analogous to the Scheme vector type, but they are distinct datatypes. An external representation is specified which must be supported by the read and write procedures and by the program parser (i.e. programs can contain references to literal homogeneous vectors).

Datatypes

There are 8 datatypes of exact integer homogeneous vectors (which will be called integer vectors):

Datatype Type of elements
s8vector signed exact integer in the range -(2^7) to (2^7)-1
u8vector unsigned exact integer in the range 0 to (2^8)-1
s16vector signed exact integer in the range -(2^15) to (2^15)-1
u16vector unsigned exact integer in the range 0 to (2^16)-1
s32vector signed exact integer in the range -(2^31) to (2^31)-1
u32vector unsigned exact integer in the range 0 to (2^32)-1
s64vector signed exact integer in the range -(2^31) to (2^31)-1
u64vector unsigned exact integer in the range 0 to (2^64)-1
s64vector signed exact integer in the range -(2^63) to (2^63)-1
u64vector unsigned exact integer in the range 0 to (2^64)-1

There are 2 datatypes of inexact real homogeneous vectors (which will be called float vectors):

Datatype Type of elements
f32vector inexact real
f64vector inexact real

The only difference between the two float vector types is that f64vectors preserve at least as much precision as f32vectors.

Each homogeneous vector datatype has an external representation which is supported by the read and write procedures and by the program parser. Each datatype also has a set of associated predefined procedures analogous to those available for Scheme's heterogeneous vectors.

External representation

[read] #u8
[read] #u16
[read] #u32
[read] #s8
[read] #s16
[read] #s32
[read] #f32
[read] #f64

The external representation of instances of the datatype XXXvector is #XXX( ...elements... ).

For example,

#u8(0 #e1e2 #xff)  ; a u8vector of length 3 containing 0, 100, 255
#f64(-1.5)         ; a f64vector of length 1 containing -1.5.

This external representation is also available in program source code. For example,

(set! x '#u8(1 2 3))

will set x to the object #u8(1 2 3). Since CHICKEN 4.9.0, literal homogeneous vectors do not have to be quoted. Homogeneous vectors can appear in quasiquotations but must not contain unquote or unquote-splicing forms. I.e.,

`(,x #u8(1 2))        ; legal
`#u8(1 ,x 2)          ; illegal

Elements may also be characters or strings, in that case they are interpreted as a sequence of numerical character codes. For example,

'#u8(#\x7f "EL" #\F 2 1)

is equivalent to

'#u8(#\x7f #\x45 #\x4c #\x46 2 1)

Character literals inside numeric vectors expand into the UTF-8 sequence of the characters they represent, for strings the contained characters are interpreted in whatever encoding is used for the text file or stream in which the literal appears.

Note that #u8"..." can be used as an abbreviation for the special case #u8("...").

Predicates

[procedure] (u8vector? OBJ)
[procedure] (s8vector? OBJ)
[procedure] (u16vector? OBJ)
[procedure] (s16vector? OBJ)
[procedure] (u32vector? OBJ)
[procedure] (s32vector? OBJ)
[procedure] (u64vector? OBJ)
[procedure] (s64vector? OBJ)
[procedure] (f32vector? OBJ)
[procedure] (f64vector? OBJ)

Return #t if obj is an object of the specified type or #f if not.

[procedure] (number-vector? OBJ)

Return #t if obj is a number vector, #f if not. A "number vector" is any of the homogeneous number vector types defined by SRFI-4, ie it's one of u8vector, s8vector, u16vector, s16vector, u32vector, s32vector, u64vector, s64vector, f32vector or f64vector).

Constructors

[procedure] (make-u8vector N [U8VALUE NONGC FINALIZE])
[procedure] (make-s8vector N [S8VALUE NONGC FINALIZE])
[procedure] (make-u16vector N [U16VALUE NONGC FINALIZE])
[procedure] (make-s16vector N [S16VALUE NONGC FINALIZE])
[procedure] (make-u32vector N [U32VALUE NONGC FINALIZE])
[procedure] (make-s32vector N [S32VALUE NONGC FINALIZE])
[procedure] (make-u64vector N [U64VALUE NONGC FINALIZE])
[procedure] (make-s64vector N [S64VALUE NONGC FINALIZE])
[procedure] (make-f32vector N [F32VALUE NONGC FINALIZE])
[procedure] (make-f64vector N [F64VALUE NONGC FINALIZE])

Return a newly-allocated SRFI-4 homogeneous number vector of length N.

If the optional fill VALUE is specified, it specifies the initial value for each slot in the vector. If not, the content of the vector is unspecified as the underlying memory is uninitialized. Particularly this means that entries in f32vector or f64vector may be i.e. a NaN-value.

The type of the fill value must be compatible with the elements of the vector datatype. It is an error if otherwise -- for example, if an inexact integer is passed to make-u8vector.

On CHICKEN, these procedures have been extended to allow allocating the storage in non-garbage collected memory, as follows:

The optional arguments NONGC and FINALIZE define whether the vector should be allocated in a memory area not subject to garbage collection and whether the associated storage should be automatically freed (using finalization) when there are no references from Scheme variables and data. NONGC defaults to #f (the vector will be located in normal garbage collected memory) and FINALIZE defaults to #t. Note that the FINALIZE argument is only used when NONGC is true.

[procedure] (u8vector U8VALUE ...)
[procedure] (s8vector S8VALUE ...)
[procedure] (u16vector U16VALUE ...)
[procedure] (s16vector S16VALUE ...)
[procedure] (u32vector U32VALUE ...)
[procedure] (s32vector S32VALUE ...)
[procedure] (u64vector U64VALUE ...)
[procedure] (s64vector S64VALUE ...)
[procedure] (f32vector F32VALUE ...)
[procedure] (f64vector F64VALUE ...)

Return a newly-allocated SRFI-4 homogeneous number vector of the specified type, composed of the arguments.

Length

[procedure] (u8vector-length U8VECTOR)
[procedure] (s8vector-length S8VECTOR)
[procedure] (u16vector-length U16VECTOR)
[procedure] (s16vector-length S16VECTOR)
[procedure] (u32vector-length U32VECTOR)
[procedure] (s32vector-length S32VECTOR)
[procedure] (u64vector-length U64VECTOR)
[procedure] (s64vector-length S64VECTOR)
[procedure] (f32vector-length F32VECTOR)
[procedure] (f64vector-length F64VECTOR)

Returns the length of the SRFI-4 homogeneous number VECTOR.

Getters

[procedure] (u8vector-ref U8VECTOR I)
[procedure] (s8vector-ref S8VECTOR i)
[procedure] (u16vector-ref U16VECTOR I)
[procedure] (s16vector-ref S16VECTOR I)
[procedure] (u32vector-ref U32VECTOR I)
[procedure] (s32vector-ref S32VECTOR I)
[procedure] (u64vector-ref U64VECTOR I)
[procedure] (s64vector-ref S64VECTOR I)
[procedure] (f32vector-ref F32VECTOR I)
[procedure] (f64vector-ref F64VECTOR I)

Return the value of the ith element of the SRFI-4 homogeneous number vector, where I is a nonnegative exact integer less than the length of the vector.

Setters

[procedure] (u8vector-set! U8VECTOR I U8VALUE)
[procedure] (s8vector-set! S8VECTOR I S8VALUE)
[procedure] (u16vector-set! U16VECTOR I U16VALUE)
[procedure] (s16vector-set! S16VECTOR I S16VALUE)
[procedure] (u32vector-set! U32VECTOR I U32VALUE)
[procedure] (s32vector-set! S32VECTOR I S32VALUE)
[procedure] (u64vector-set! U64VECTOR I U64VALUE)
[procedure] (s64vector-set! S64VECTOR I S64VALUE)
[procedure] (f32vector-set! F32VECTOR I F32VALUE)
[procedure] (f64vector-set! F64VECTOR I F64VALUE)

Set the ith element of the SRFI-4 homogeneous number VECTOR to VALUE. I is a nonnegative exact integer less than the length of the vector and VALUE must be the same type as the elements of the vector datatype.

Additionally, SRFI-17 setters are defined on all xxxvector-ref procedures. For example, to set the ith element of SRFI-4 u8vector to u8value:

(set! (u8vector-ref u8vector i) u8value)

Conversions

[procedure] (u8vector->list U8VECTOR)
[procedure] (s8vector->list S8VECTOR)
[procedure] (u16vector->list U16VECTOR)
[procedure] (s16vector->list S16VECTOR)
[procedure] (u32vector->list U32VECTOR)
[procedure] (s32vector->list S32VECTOR)
[procedure] (u64vector->list U64VECTOR)
[procedure] (s64vector->list S64VECTOR)
[procedure] (f32vector->list F32VECTOR)
[procedure] (f64vector->list F64VECTOR)

Return a list consisting of the elements of SRFI-4 homogeneous number VECTOR.

[procedure] (list->u8vector U8LIST)
[procedure] (list->s8vector S8LIST)
[procedure] (list->u16vector U16LIST)
[procedure] (list->s16vector S16LIST)
[procedure] (list->u32vector U32LIST)
[procedure] (list->s32vector S32LIST)
[procedure] (list->u64vector U64LIST)
[procedure] (list->s64vector S64LIST)
[procedure] (list->f32vector F32LIST)
[procedure] (list->f64vector F64LIST)

Return a newly-allocated SRFI-4 homogeneous number VECTOR consisting of the elements of LIST. Each element of LIST must be compatible with the datatype of VECTOR.

Release number vectors allocated in static memory

[procedure] (release-number-vector NVECTOR)

Release the storage of a SRFI-4 vector that was allocated in non-garbage collected memory (for example using the NONGC argument for one of the make-XXXvector constructor procedures). The effect of calling this procedure with a number vector allocated in normal garbage collected memory is undefined.

Previous: Module r4rs

Next: Module (chicken base)